Amazon S3マニフェストファイル詳解：QuickSightでサポートされているファイル取り込み指定方法 #quicksight #23 | Amazon QuickSight Advent Calendar 2016

当エントリは『Amazon QuickSight Advent Calendar 2016』の23本目のエントリです。

• Amazon QuickSight (全部俺) Advent Calendar 2016 - Qiita

昨日の22本目のエントリは『データソースに関する制限』でした。

• データソースに関する制限 #quicksight #22 | Amazon QuickSight Advent Calendar 2016 ｜ Developers.IO

『AWS re:Invent 2016』の直前に一般利用可能となったAWSによるBIサービス、Amazon QuickSight。発表されたばかりですが、早速Amazon QuickSightを使い倒すべく色々な切り口でその内容について見て行きたいと思います。

23本目となる当エントリでは、Amazon QuickSightにおける『QuickSightでサポートされているファイル取り込み指定方法』について見て行きたいと思います。

Amaozn QuickSightではJSONマニフェストファイルを使ってAmazon S3のファイルを指定し、インポートを行う事が出来ます。これらのJSONマニフェストについては後述する形式を使用する事が出来ます。形式はAmazon QuickSight形式／Amazon Redshift形式の2つがあります。

• マニフェストを使用し、データファイルを指定する - Amazon Redshift

Amazon QuickSightマニフェストファイルを使用する場合、拡張子：jsonが必要です(例：my_manifest.json)。Amazon Redshiftマニフェストファイルを使用する場合は任意の拡張子を付ける事が可能です。Amazon Redshiftマニフェストファイルを使用している場合、Amazon Redshiftと同様にAmazon QuickSightはオプションの必須フラグを処理しインポートプロセスを実施、関連付けられたファイルが見つからない場合はエラーを返します。

インポートするファイルについては任意の区切り文字を使用したファイル(.CSV, *.TSV)、ログ(.clf)、拡張ログ(*.elf)のいずれかである必要があります。また1つのマニフェストファイルで扱うファイルの拡張子は1つに統一しなければなりません(混在不可)。

マニフェストで指定されたファイルは1GBを超えることはできず、指定されたすべてのファイルの合計サイズは10GBを超えることはできず、指定されたファイルの総数は100を超えることはできません。

指定したファイルは、Amazon QuickSightへのアクセスを許可したAmazon S3バケット内にある必要があります。 AWSリソースへのAmazon QuickSightアクセスの許可については、下記をご参照ください。

• Managing Amazon QuickSight Permissions to AWS Resources - Amazon QuickSight

Amazon QuickSightマニフェストファイルフォーマット

Amazon QuickSightマニフェストファイルのJSONフォーマットは以下の形式となります。

{ 
    "fileLocations": [                                                    
          {"URIs": ["uri1", "uri2", "uri3"]},
          {"URIPrefixes": ["prefix1", "prefix2", "prefix3"]}
     ],
     "globalUploadSettings": { 
         "format": "CSV",  
         "delimiter": ",",         
         "textqualifier": "'",    
         "containsHeader": "true" 
    }
}

fileLocations エレメントにてインポートするファイルを指定、globalUploadSettings エレメントにてインポートするファイルに関する設定(区切り文字など)を指定します。

マニフェストファイルの各種エレメントの詳細な内容は以下の通りです。

fileLocations

インポート対象のファイルを指定する箇所。URIsまたはURIPrefixesの配列を利用する事が出来ます。少なくとも1つの値を指定する必要があります。

URIs

インポート対象のファイルをURIのリスト形式で指定。Amazon QuickSightはAmazon どのリージョンのS3のファイルにもアクセスする事が出来ますが、Amazon QuickSightアカウントが使われているリージョンとバケットのリージョンが異なる場合、Amazon S3バケットのリージョンを指し示すURIフォーマットを使わなければなりません。利用可能なURIsのフォーマットは以下の通りです。

(※1):このURIタイプは、Amazon S3バケットの領域を識別します。

URIPrefixes

S3バケットのURIの一覧にこの配列を使用します。

指定されたバケット内全てのファイルがインポートされます。Amazon QuickSightは子フォルダのファイル群を再帰的には取得しません(ので気を付けて下さい)。Amazon QuickSightは全リージョンのAmazon S3バケットにアクセス可能です。しかし、Amazon QuickSightのアカウントとリージョンが異なる場合は、この値にはリージョンを指し示すフォーマットを指定する必要があります。サポートされているURIPrefixesのフォーマットは以下の通りです。

(※1):このURIPrefixタイプは、Amazon S3バケットの領域を識別します。

globalUploadSettings

(オプション)この要素は、Amazon S3ファイルに対するインポート設定(区切り文字等)を指定する際に使用します。もし要素が指定されていない場合、Amazon QuickSightは以下項目毎に定められているデフォルト値を使用します。

format

(オプション)インポート対象ファイルの形式を指定。有効な値はCSV, TSV, CLF, ELF。(※デフォルト値：CSV)

delimiter

(オプション)ファイルの区切り文字を指定。[format]フィールドで指定されたファイルタイプと対応している必要があります。有効な形式はCSV形式の場合はカンマ(,)、TSV形式の場合はタブ文字(\t)となります。(※デフォルト値：カンマ(,))

textqualifier

(オプション)ファイルの『囲み文字』を指定。有効な値はシングルクォート('), ダブルクォート(\")。 先頭のバックスラッシュはJSONファイル内でのダブルクォート文字に対して必要なエスケープ文字です。囲み文字が使われていない場合、その項目は値が無い状態となります。(※デフォルト値：ダブルクォート(\"))

containsHeader

(オプション)ファイルがヘッダ行を含むか含まないかを指定。有効値はtrue or false。デフォルト値はtrue。

Amazon QuickSightマニフェストファイルのサンプル

例1:

以下1つ目のサンプルではインポート対象のCSVファイル2つをマニフェストファイルで指定しています。

これらのファイルは囲み文字にダブルクォート(\")を使っています。format,delimiter,containsHeaderフィールドの値に関してはデフォルト値が適用されます。

{ 
    "fileLocations": [                                                    
          {"URIs": [
              "https://data_bucket.s3.amazonaws.com/data.csv",
              "https://data_bucket.s3.amazonaws.com/data2.csv"
           ]}
     ],
     "globalUploadSettings": { 
         "textqualifier": "\""    
    }
}

例2:

2つ目のサンプルがこちら。対象ファイルとなるTSVを2つ指定し、1つはURI指定、もう1つはURIプレフィックス指定で異なるリージョンの任意のバケット全体を指し示しています。textqualifierとcontainsHeaderフィールドについてはデフォルト値が適用されます。

{ 
    "fileLocations": [                                                    
          {"URIs": [
               "https://s3.amazonaws.com/data_bucket/data.tsv"
          ]},
          {"URIPrefixes": [
               "https://s3-us-east-1.amazonaws.com/data_bucket/"
          ]}
     ],
     "globalUploadSettings": { 
         "format": "TSV",  
         "delimiter": "\t"         
    }
}

例3:

3つ目のサンプル。URIプレフィックス指定で異なる表現方法でバケット2つを指定しています。対象ファイルはformatにてCLFを指定。 delimiter, textqualifier, containsHeaderについてはログファイル取り込みの為、指定しても無視されます。

{ 
    "fileLocations": [                                                    
          {"URIPrefixes": [
              "https://data_bucket.s3-us-east-1.amazonaws.com",
              "s3://other_data_bucket/"
          ]}
     ],
     "globalUploadSettings": { 
         "format": "CLF" 
    }
}

例4:

4つ目のサンプル。Amazon Redshift形式を使用して、インポートする.csvファイルを識別します。

{
  "entries": [
    {"url":"https://s3-us-west-2.amazonaws.com/carpc-test/Consumer_Complaints3.csv", "mandatory":true}
  ]
}

まとめ

という訳で『Amazon QuickSight Advent Calendar 2016』23本目、『QuickSightでサポートされているファイル取り込み指定方法』に関するご紹介でした。明日もお楽しみに！

参考情報

• Supported Formats for Amazon S3 Manifest Files - Amazon QuickSight